<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Enumerator</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>Enumerator Object <span class="ver">[AHK_L 49+]</span></h1>

<p>Allows items in a collection to be enumerated.</p>

<div class="methodShort">
<h2 id="Next">Next</h2>

<p>Retrieves the next item or items in an enumeration.</p>
<pre class="Syntax">Enum.Next(OutputVar1 [, OutputVar2, ...])</pre>
<table class="info">
  <tr><td width="15%">OutputVar1, OutputVar2</td><td width="85%">Receives an implementation-specific value.</td></tr>
  <tr><td>...</td><td>Additional parameters, if supported.</td></tr>
  <tr><td><b>Returns</b></td><td>A non-zero integer if successful, zero if there were no items remaining, or an empty string if parameters were incorrect.</td></tr>
</table>

<h3>Object</h3>
<p>Enumerators returned by <a href="Object.htm#NewEnum">ObjNewEnum()</a> are called once for each key-value pair, and allow up to two parameters:</p>
<table class="info">
  <tr><td width="15%">OutputVar1</td><td width="85%">Receives the <b>key</b> in a key-value pair.</td></tr>
  <tr><td>OutputVar2</td><td>Receives the <b>value</b> associated with <i>OutputVar1</i>.</td></tr>
</table>
<p>Key-value pairs are returned in an implementation-defined order. That is, they are typically not returned in the same order that they were assigned. Existing key-value pairs may be modified during enumeration, but inserting or removing keys may cause some items to be enumerated multiple times or not at all.</p>

<h3>Related</h3>
<a href="../commands/For.htm">For-loop</a>, <a href="Object.htm#NewEnum">Object.NewEnum()</a>

<h3>Example</h3>
<pre class="NoIndent"><em>; Create some sample data.</em>
obj := Object("red", 0xFF0000, "blue", 0x0000FF, "green", 0x00FF00)

<em>; Enumerate!</em>
enum := obj._NewEnum()
While enum[k, v]
    t .= k "=" v "`n"
MsgBox % t

<em>; AHK_L 59+</em>
For k, v in obj
    s .= k "=" v "`n"
MsgBox % s
</pre>
</div>

</body>
</html>
